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PURPOSE:  The  purpose  of  this  Coastal  and  Hydraulics  Engineering  Technical  Note  (CHETN)  is 
to  describe  the  graphical  interface  for  the  full-plane  version  of  the  wave  model  STWAVE  (Smith 
et  al.  2001;  Smith  2001;  and  Smith  and  Smith  2002)  that  has  been  added  to  the  U.S.  Army  Corps 
of  Engineers  (USACE)  Surface  Water  Modeling  System  (SMS).  A  subsequent  publication  will 
describe  the  capabilities  added  in  the  full  plane  version  of  the  model. 

BACKGROUND:  STWAVE  solves  the  steady-state  conservation  of  spectral  wave  action  along 
backward  traced  wave  rays  (Smith  2001).  The  model  is  used  to  compute  wave  transformation 
(refraction,  shoaling,  and  breaking)  and  wind-wave  generation.  Previous  versions  of  STWAVE 
operated  on  a  half  plane,  meaning  that  only  wave  energy  traveling  within  a  180-deg  arc  is 
considered  (i.e.,  wave  energy  propagating  from  offshore  to  the  beach).  The  half-plane  assumption 
is  appropriate  for  most  open  coast  applications,  but  for  bays,  lakes,  or  complex  shorelines,  wave 
transformation  and  generation  on  the  full  360-deg  plane  is  required.  The  full-plane  version  of 
STWAVE  (STWAVE-FP)  includes  several  changes  to  model  input,  output,  and  modeling 
procedures.  These  include  the  potential  specification  of  spectral  inputs  on  all  edges  of  the 
computational  domain,  additional  model  parameters,  and  new  file  formats.  This  CHETN  describes 
the  interface  developed  for  STWAVE-FP  and  the  file  formats  associated  with  the  model. 

STWAVE-FP  FILES:  Four  input  files  are  required  for  an  STWAVE-FP  simulation  (Figure  1), 
which  include  the  simulation  (*.sim),  the  model  parameters  (*.std),  the  depths  (*.dep),  and  the 
input  spectra  (*.eng).  Current  (*.cur)  and  structures  (*. struct)  files  are  optional.  The  name  of  the 
simulation  file  can  be  passed  to  the  STWAVE-FP  model  as  a  command  line  argument  or  the  model 
may  be  launched  from  inside  of  SMS.  Depending  on  the  options  selected,  STWAVE-FP  creates 
between  one  and  five  output  files  (Figure  1).  The  wave  field  file  (*.wav)  is  always  generated  and 
provides  the  wave  height,  peak  period,  and  mean  wave  directions  over  the  entire  STWAVE-FP 
grid.  Optional  output  files  include  output  spectra  at  selected  cells  (*.obs),  output  spectra  at  nesting 
cells  (*.nst),  wave  breaking  information  (*.brk),  and  wave  radiation  stress  gradients  (*.rad). 

The  simulation  file  stores  the  names  of  all  the  files  that  contain  data  related  to  the  simulation.  This 
includes  the  files  used  by  STWAVE-FP  and  three  other  files  that  are  used  by  the  SMS  interface. 
These  additional  files  contain  parameters  used  to  define  the  input  spectra  (*.txt),  a  filtered  list  of 
the  input  spectra  (*.wavespec),  and  a  mapping  of  which  spectra  are  applied  to  which  grid 
boundaries  for  individual  wave  cases  (*.stc).  All  the  potential  input  and  output  files  are  listed  in 
Figure  1 ,  and  a  description  of  each  file  is  given  in  Table  1 .  All  STWAVE  input  and  output  files  are 
in  SI  units,  but  the  user  can  work  in  non-SI  units  in  SMS,  and  SMS  will  automatically  convert  to 
SI  units  when  the  files  are  saved. 
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Required  input  files 

projname.slm 
projname.  std 
proj name. dep 
projname. eng 

V  STWAVE-FP 

Optional  input  files 
projname. enr 
projname. struct 

J 

f 

< 


Output  files 

projname.  wav 


Optional  output  files 
projname.  obs 
projname.  nst 
pro j name. bxk 
projname. rad 


Figure  1.  Files  involved  in  STWAVE-FP  simulation 


Table  1 

Files  Involved  in  STWAVE-FP  Simulation 

File  Name 

Type 

Description 

projname.  sim 

Input  -  required 

Input  and  output  filenames  for  the  simulation 

projname.  std 

Input  -  required 

Model  parameters  and  output  options 

projname.dep 

Input  -  required 

Water  depths  at  all  grid  cells 

projname.e  ng 

Input  -  optional 

Input  wave  energy  spectra  -  this  includes  one  spectra  for  each  open  boundary  for  each  wave 
case.  Wave  spectra  may  be  repeated 

projname.  struct 

Input -optional 

List  of  cells  containing  structures 

projname.  cur 

Input  -  optional 

Current  at  each  cell  (u,  v  components  in  x,y  directions). 

projname.  wav 

Output  -  always 

Wave  height,  period  and  direction  for  each  cell 

projname.  obs 

Output  -  optional 

Transformed  energy  spectra  at  selected  cells 

projname.  nst 

Output  -  optional 

Transformed  energy  spectra  at  cells  to  input  to  nested  grid  simulation 

projname.  brk 

Output  -  optional 

Breaking  flag  or  energy  dissipated  at  each  cell  due  to  breaking  (depending  on  breaking 
option)  1 

projname.  rad 

Output  -  optional 

Radiation  stress  gradients  (in  x,y  directions)  at  each  cell 

STWAVE-FP  INTERFACE:  The  interface  for  the  full-plane  version  includes  the  same 
components  as  the  interface  for  the  half-plane  version.  The  same  general  modeling  steps,  outlined 
in  Smith  (2001)  are  still  recommended.  In  this  document,  the  principal  components  of  the  interface 
will  be  presented.  Differences  specific  to  the  full-plane  version  are  highlighted. 


Like  other  finite-difference  models  in  SMS,  STWAVE-FP  is  controlled  through  the  2D  Cartesian 
Grid  Module  EBi.  The  user  should  select  the  Set  Current  Model  command  in  the  Edit  menu  and 


choose  STWA  VE-FP  to  activate  the  model  interface.  When  STWAVE-FP  is  selected  as  the  current 
model,  the  STWAVE-FP  menu  and  tools  become  available.  It  is  recommended  that  the  user 
become  familiar  with  other  modules  of  SMS  to  fully  exploit  the  interface.  For  example,  the 
STWAVE-FP  grid  can  also  be  specified  in  the  Map  Module  via  a  STWA  VE-FP  Coverage.  In 
addition,  in  most  simulations  the  user  will  use  the  Scatter  Module  **  to  import  surveys  and  digital 
maps  to  define  bathymetry  for  a  grid. 


STWAVE-FP  Menu.  The  STWAVE-FP  menu  (Figure  2)  commands  are  listed  in  Table  2  along 
with  a  description  of  each  command. 
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j 

Spectra? 


Window  Help 


Spectra?  Energy 


Assign  Cell  Attributes. . . 

Genesis  Observation  Stations... 
Nest  Grid 


Model  Control... 
Run  ST  WAVE... 


Figure  2.  STWAVE-FP  menu 


Table  2 

STWAVE-FP  Menu  Commands 

Command 

Functionality 

Spectral  Energy 

Brings  up  the  spectral  energy  dialog  to  define/view  wave  energy  spectra  to  be  used  in  this  simulation. 

Spectral  generation  is  described  in  its  own  section. 

Assign  Cell 
Attributes 

This  command  is  used  to  assign  cell  attributes.  A  cell  can  be  a  typical  ocean  cell,  a  special  ocean  cell 
(spectral  output  computed  at  these),  a  typical  land  cell,  or  a  structural  cell. 

Genesis 

Observation 

Stations 

This  command  is  only  available  when  a  Genesis  grid  is  loaded  into  the  SMS.  This  command  places 
observation  cells  to  correspond  to  the  Genesis  grid. 

Nest  Grid 

This  command  is  available  when  multiple  grids  are  loaded  into  the  SMS.  It  allows  parent-child  relationships 
to  be  created  between  the  grids. 

Model  Control 

Brings  up  the  Model  Control  dialog  to  specify  model  parameters. 

Run  STWAVE-FP 

Launches  STWAVE-FP  with  the  currently  loaded  simulation.  As  the  model  runs,  a  dialog  monitors  progress 
of  the  model  and  gives  the  user  status  messages.  When  the  run  is  complete,  the  spatial  solutions  are  read  in 
for  analysis  and  visualization. 

STWAVE-FP  Tools.  The  STWAVE-FP  tools  are  listed  in  Table  3  along  with  their  icon  and 
functionality.  In  SMS,  one  tool  is  active  at  a  time.  The  active  tool  may  be  a  model  specific  tool 
such  as  those  listed  in  the  following  table,  or  it  may  be  a  general  tool  such  as  Pan,  Zoom,  or 
Rotate.  The  active  tool  controls  what  response  the  program  will  make  when  the  user  clicks  or 
drags  the  mouse  through  the  graphics  window.  Typically  there  are  two  types  of  tools,  those  that 
are  used  to  select  entities  and  those  that  are  used  to  create  entities.  In  the  STWAVE-FP  interface, 
the  user  can  create  a  grid  and  then  select  cells  within  that  grid.  Multiple  cells  can  be  selected  using 
the  tools  for  selecting  columns  or  rows,  or  by  dragging  a  box  or  polygon  around  more  than  one 
entity,  or  by  holding  down  the  SHIFT  key  while  sequentially  clicking  on  entities. 
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Table  3 

STWAVE-FP  Tools 

Tool 

Icon 

Functionality 

Select 

Cell 

E3 

Allows  the  user  to  select  a  computation  point  (cell)  by  graphically  clicking  on  it.  STWAVE-FP  works  on  a  “cell 
centered”  grid  meaning  that  its  computation  points  are  at  the  centers  of  the  cells.  Once  selected,  the  user  can 
adjust  the  elevation  of  the  cells  or  assign  them  attributes. 

Select 

Row 

El 

Allows  the  user  to  select  an  entire  row  of  cells  by  clicking  on  any  cell  in  the  row. 

Select 

Column 

M 

Allows  the  user  to  select  an  entire  column  of  cells  by  clicking  on  any  cell  in  the  column. 

Create 

Grid 

ffl 

Allows  the  user  to  create  a  computational  grid  by  clicking  three  corners  of  the  grid. 

Creating  a  Grid.  The  process  for  creating  a  STWAVE-FP  model  grid  consists  of  four  steps: 

a.  Read  in  bathymetric  data.  These  data  can  be  from  one  or  more  surveys,  or  from  another 
numerical  model  simulation  (e.g.,  an  ADCIRC  mesh  converted  to  a  scatter  set).  Data  should  be 
brought  into  SMS  as  a  scattered  data  set  or  a  digital  elevation  map  (DEM).  The  most  common 
formats  are  described  as  an  *.xyz  or  *.pts  fde  in  the  SMS  documentation.  Data  for  the  coastlines 
and  structures  in  the  modeling  domain  could  either  be  included  in  the  bathymetry  (recommended) 
or  brought  into  SMS  separately  and  merged  with  the  bathymetry  data  inside  SMS.  Within 
STWAVE-FP,  water  depths  are  positive  numbers  and  land  elevations  are  negative  numbers. 
STWAVE  operates  in  a  Cartesian  coordinate  system,  so  bathymetry  in  geographic  coordinates 
must  be  converted  to  State  Plane  or  UTM  prior  to  creating  the  grid.  SMS  offers  a  number  of 
coordinate  conversions  (Zundel  2005). 

b.  Select  STWA  VE-FP  as  the  working  model.  In  the  Cartesian  Grid  Module  S9,  under  Data 
menu,  find  Switch  Current  Model  submenu  and  select  STWA  VE-FP  as  the  working  model. 

c.  Define  modeling  domain.  Zoom  into  the  area  around  the  computational  domain  and  select 
the  create  grid  tool  EEL  To  define  the  extent  of  the  modeling  domain,  the  user  must  click  three 
times  in  the  graphics  window.  The  first  click  (Pt  1)  is  at  the  grid  origin  (STWAVE  local x  =  0 ,y  = 
0).  Then  the  user  should  move  the  cursor  (a  line  will  appear  from  the  selected  comer)  along  the 
STWAVE-FP  x-axis  and  click  again  (Pt  2).  Finally,  the  user  must  move  the  cursor  to  define  the 
extent  of  the  y-axis  and  click  again  (Pt  3).  Figure  3  shows  a  grid  being  defined. 

d.  Create  a  grid.  After  defining  the  grid  domain,  the  Map->2D  Grid  dialog  appears 
(Figure  4).  This  dialog  allows  the  user  to  modify  the  size,  orientation,  position  and  cell  size  for  the 
grid  that  is  being  created.  The  grid  position  and  orientation  are  initialized  from  the  three  points 
digitized  in  the  previous  step.  If  more  exact  locations  are  known,  the  user  would  enter  these  in  the 
top  section  of  the  dialog.  In  the  center  section,  the  individual  cell  size  is  entered.  Previous  versions 
of  STWAVE  supported  only  square  cells;  however,  STWAVE-FP  is  more  general  and  allows 
rectangular  cells.  The  default  values  create  a  grid  with  10  x  10  cells,  so  these  values  must  be 
changed  by  the  user  to  the  desired  values.  In  the  lower  section  of  this  dialog,  users  tell  SMS  to 
interpolate  the  bathymetry  values  for  the  grid  from  the  scattered  data.  There  is  also  an  option  to 
interpolate  current  data  to  the  grid.  Once  these  data  are  entered,  the  user  clicks  the  OK  button,  and 
a  grid  is  created.  Bathymetry  values  for  each  cell  of  the  grid  (along  with  current  values  if  that  was 
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specified)  will  be  interpolated  from  the  scattered  bathymetry  data  to  the  cell  centroids.  Grid  cells 
with  a  negative  depth  value  will  be  classified  as  dry  land  and  excluded  in  the  STWAVE-FP 
calculations.  After  the  grid  is  created,  the  user  can  also  select  cells  and  modify  depth  values  and 
cell  classifications. 


Figure  4.  Map  ->2D  grid  dialog 


Editing  a  Grid.  Cell  depths  and  attributes  in  the  STWAVE-FP  grid  may  be  edited,  but  the  grid 
itself  cannot  be  repositioned  once  it  is  generated.  To  reposition  or  change  the  resolution  of  a  grid,  a 
new  grid  should  be  created.  This  is  required  if  the  domain  is  enlarged  or  reduced,  the  grid  cell  size 
is  modified,  or  the  grid  orientation  is  adjusted  to  align  with  principal  wave  directions.  Various 
operations  are  permitted  for  editing  STWAVE-FP  grid  cells.  These  include: 

a.  Specification  of  individual  cell  depth/elevation.  Select  one  or  more  cells  using  the  select 
cell  tool  S3,  and  specify  a  depth/elevation  value  in  the  edit  field  located  at  the  top  of  the 
application  (just  below  the  menus).  This  feature  could  be  used  to  represent  the  effects  of  a 
dredging  or  shoal-mining  on  the  wave  field  by  deepening  areas  in  the  grid  or  represent  the  effect  of 
dredged  material  mounds  in  the  modeling  domain  by  reducing  depths,  etc.  This  feature  is  useful 
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when  changes  to  the  underlying  bathymetry  are  desired  in  a  small  section  of  the  modeling  domain 
where  such  changes  can  be  made  manually  to  a  subarea  or  selection  of  cells. 

b.  Classification  of  grid  cells  as  land,  structure,  water,  or  monitoring  station  (special  output) 
location.  This  is  done  by  selecting  one  or  more  nodes  using  the  Select  Cell  tool  EH  and  specifying 
the  cell  attributes  using  the  Assign  Cell  Attributes  command  in  the  STWAVE-FP  menu.  This 
brings  up  the  STWAVE-FP  Cell  Attributes  dialog.  Wave  spectra  (.obs  file)  and  a  summary  file  of 
wave  parameters  (selhts  file)  will  be  written  out  for  the  monitoring  station  location(s). 

Defining  Spectra.  Boundaries  conditions  for  STWAVE-FP  consist  of  energy  spectra  at  open 
boundaries.  This  requires  that  the  user  define  these  spectra.  The  spectra  can  be  generated  from  an 
external  source,  and  read  in  from  an  energy  “.eng”  file,  or  created  using  the  spectral  energy 
command  in  the  menu.  This  brings  up  the  Spectral  Energy  dialog  shown  in  Figure  6.  To  generate 
spectra,  the  user  must  first  create  a  spectral  grid.  The  Create  Grid  button  allows  the  user  to  specify 
the  number  and  distribution  of  frequencies  and  the  directional  bin  size. 


Cell  Attributes 


Cell  Type 


Ocean 
C  Land 

■'  Monitoring  Station 
Nesting  Output 


Cancel 


Figure  5.  STWAVE-FP  Cell  Attributes  Figure  6. 
dialog 


Spectral  Energy  dialog  for  spectra  visualization  and 
generation 


Once  the  spectral  grid  exists,  the  user  can  use  the  Generate  Spectra  button  to  generate  spectra  from 
parameters.  The  spectral  types  supported  are  shown  in  Table  4.  Parameters  used  to  generate 
spectra  are  stored  in  a  tabular  text  file  with  the  simulation  for  later  reference.  As  can  be  seen  in 
Figure  6,  the  spectra  cover  the  full  360-deg  plane.  The  dialog  allows  the  visualization  of  the 
spectra  in  three  dimensions  and  integrated  frequency  and  directional  distributions. 
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Table  4 

Spectral  Parameters 

Spectral  Shape 

Required  Parameters 

TMA  (Arbitrary  Water  Depth) 

Significant  Wave  Height  (Hs) 

Peak  Wave  Period  (Tp) 

Gamma  (frequency  spread) 
nn  (directional  spread) 

Minimum  Wave  Period  (Tmin) 

Maximum  Wave  Period  (Tmax) 

Whether  to  rescale  the  spectrum  or  not 

JONSWAP 

Hs  and  Tp  or  Wind  Speed  and  Fetch  Distance 
Gamma 

Minimum  Wave  Period  (Tmin) 

Maximum  Wave  Period  (Tmax) 

Whether  to  rescale  the  spectrum  or  not 

Bretschneider  (ITTC) 

Significant  Wave  Height  (Hs) 

Peak  Wave  Period  (Tp) 

Minimum  Wave  Period  (Tmin) 

Maximum  Wave  Period  (Tmax) 

Whether  to  rescale  the  spectrum  or  not 

Pierson-Moskowitz 

Wind  Speed  or  Hs  or  Tp 

Minimum  Wave  Period  (Tmin) 

Maximum  Wave  Period  (Tmax) 

Whether  to  rescale  the  spectrum  or  not 

Ochi-Hubble  Double  Peak 

Hs  for  the  low  frequency 

Hs  for  the  high  frequency 

Tp  for  the  low  frequency 

Tp  for  the  high  frequency 

Gamma  for  the  low  frequency 

Gamma  for  the  high  frequency 

Minimum  Wave  Period  (Tmin) 

Maximum  Wave  Period  (Tmax) 

Whether  to  rescale  the  spectrum  or  not 

Model  Control  Parameters.  The  Model  Control  command  in  the  STWAVE-FP  menu  brings  up 
the  Model  Control  dialog  shown  in  Figure  7. 


Figure  7.  STWAVE-FP  Model  Control  dialog 
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This  dialog  is  divided  into  two  parts  as  follows: 

a.  Grid  definition.  This  section  describes  the  grid.  It  is  for  information  only  and  can  not  be 
modified. 

b.  Model  settings.  This  section  includes  combination  boxes  for  model  settings  including 
computational  options  and  output  options.  It  also  includes  a  button  to  set  the  boundary  conditions 
for  each  wave  case  to  be  considered  and  a  toggle  to  tell  SMS  whether  to  interpret  these  cases  as 
individual  scenarios  or  quasi-time-steps  of  events. 

•  Set  boundary  conditions.  STWAVE-FP  allows  input  of  multiple  wave  cases  or  events  in 
a  single  run.  Further,  each  edge  of  the  domain  may  potentially  have  waves  entering  across  the 
boundary.  The  Set  Boundary  Conditions  button  in  the  model  control  brings  up  the  STWA  VE 
Boundary  Condition  dialog  (Figure  8).  In  the  upper  left  quadrant  of  the  dialog,  the  user  selects  the 
type  of  boundary  for  each  of  the  four  edges  of  the  domain.  This  can  be  a  zero  spectrum  (land  or 
open  boundary),  1-D  transformed  spectrum  (lateral  boundary,  waves  are  transformed  along  the 
boundary  assuming  the  bathymetry  is  1-D),  or  spectrum  from  fde  (specified  wave  spectra,  see 
Defining  Spectra).  In  the  lower  left  quadrant,  the  user  defines  the  number  of  wave  cases  to  be 
simulated.  Each  row  of  the  spreadsheet  defines  a  case  to  be  simulated.  For  each  case,  the  user 
defines  the  wind  direction,  magnitude,  tidal/surge  elevation  and  input  spectrum  (for  each  boundary 
that  needs  a  spectrum).  These  are  chosen  by  selecting  the  cell  in  the  spreadsheet,  and  double 
clicking  in  the  list  of  defined  spectra  that  appears  on  the  right  side  of  the  dialog. 


Figure  8.  Wave  case  Boundary  Condition  dialog 
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•  Source  terms.  This  option  can  be  either  Source  Terms  and  Prop,  or  Propagation  Only. 
If  propagation  only  is  chosen,  no  wind  wave  growth  is  included  in  the  simulation  (and  the 
simulation  executes  faster). 

•  Wave  current.  Presently,  the  full-plane  version  of  STWAVE  does  not  include  wave- 
current  interaction.  The  options  in  the  future  will  be  none  for  no  wave-current  interaction,  currents 
for  including  wave-current  interaction,  and  constant  for  all  spectra  for  a  single  current  field 
applied  to  all  input  conditions.  The  options  with  currents  will  require  a  projname.cur  input  file. 

•  Breaking.  This  option  allows  the  user  to  identify  where  within  the  grid  waves  are 
breaking.  The  option  write  indices  will  write  out  a  field  of  ones  (for  breaking)  and  zeros  (for  no 
breaking)  to  the  projname.brk  file  to  identify  breaking  locations.  The  option  no  indices  will  not 
create  breaking  file. 

•  Radiation  stresses.  This  option  specifies  whether  radiation  stresses  will  be  calculated 
( calculated)  or  not  (none).  Radiation  stresses  are  wave  momentum  fluxes  that  can  be  fed  into  a 
circulation  model  to  generate  wave  setup  and  nearshore  currents. 

•  Number  of  iterations.  Waves  in  shallow  water  can  refract  significantly,  so  wave 
propagation  cannot  always  be  solved  in  four  progressive  sweeps  of  the  grid.  Thus,  for  complex 
areas,  multiple  iterations  may  be  required  in  the  model.  The  number  of  iterations  is  specified  here. 

•  Use  time-steps.  STWAVE-FP  is  a  steady-state  model,  but  it  can  be  run  in  a  quasi-time 
stepping  mode  (series  of  steady  simulations).  This  option  lets  the  user  identify  times  to  case  or 
event  identifier. 

SUMMARY:  Various  features,  tools,  and  analysis  capabilities  outlined  in  this  document  are 
designed  to  enhance  the  ability  of  engineers  to  efficiently  utilize  the  STWAVE-FP  in  SMS.  This 
CHETN  provides  specific  guidance  to  users  to  ensure  a  comprehensive  understanding  of  the 
interface  necessary  for  the  most  efficient  usage  of  STWAVE-FP.  With  the  usage  of  the  model  in 
engineering  projects  by  the  user  community,  both  the  model  and  its  interface  are  expected  to 
evolve,  and  the  current  interface  will  continue  to  undergo  revisions.  Feedback  and  suggestions 
from  users  on  the  design,  implementation,  and  usage  of  the  present  version  of  the  STWAVE-FP 
interface  are  welcome. 

ADDITIONAL  INFORMATION:  The  Transformation-Scale  Waves  work  unit  of  the  U.S.  Army 
Corps  of  Engineers,  Navigation  Systems  Research  Program,  funded  this  research.  Questions  about 
this  CHETN  can  be  addressed  to  Dr.  Jane  McKee  Smith  (601-634-2079,  e-mail: 
Jane.M.Smith@erdc.usace.army.mil ).  This  CHETN  should  be  referenced  as  follows: 

Smith,  J.  M.,  and  Zundel,  A.  (2006).  STWAVE-FP  in  SMS:  Graphical  interface. 

Coastal  and  Hydraulics  Engineering  Technical  Note  CHETN  1-69,  U.S.  Army 

Engineer  Research  and  Development  Center,  Vicksburg,  MS. 

http:  //chi.  wes.  army.mil/library/publications/chetn/ 
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